home *** CD-ROM | disk | FTP | other *** search
/ PC Advisor 2011 May / PC Advisor 190 E.iso / pc / ESSENTIALS / VLC Media Player 1.1 / vlc-1.1.5-win32.exe / sdk / include / vlc / plugins / vlc_picture.h < prev    next >
Encoding:
C/C++ Source or Header  |  2010-11-13  |  11.8 KB  |  358 lines
  1. /*****************************************************************************
  2.  * vlc_picture.h: picture definitions
  3.  *****************************************************************************
  4.  * Copyright (C) 1999 - 2009 the VideoLAN team
  5.  * $Id: 52c23b280b2fd758b16d093f9ec1f04d0241f0db $
  6.  *
  7.  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  8.  *          Samuel Hocevar <sam@via.ecp.fr>
  9.  *          Olivier Aubert <oaubert 47 videolan d07 org>
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24.  *****************************************************************************/
  25.  
  26. #ifndef VLC_PICTURE_H
  27. #define VLC_PICTURE_H 1
  28.  
  29. /**
  30.  * \file
  31.  * This file defines picture structures and functions in vlc
  32.  */
  33.  
  34. #include <vlc_es.h>
  35.  
  36. /** Description of a planar graphic field */
  37. typedef struct plane_t
  38. {
  39.     uint8_t *p_pixels;                        /**< Start of the plane's data */
  40.  
  41.     /* Variables used for fast memcpy operations */
  42.     int i_lines;           /**< Number of lines, including margins */
  43.     int i_pitch;           /**< Number of bytes in a line, including margins */
  44.  
  45.     /** Size of a macropixel, defaults to 1 */
  46.     int i_pixel_pitch;
  47.  
  48.     /* Variables used for pictures with margins */
  49.     int i_visible_lines;            /**< How many visible lines are there ? */
  50.     int i_visible_pitch;            /**< How many visible pixels are there ? */
  51.  
  52. } plane_t;
  53.  
  54. /**
  55.  * Maximum number of plane for a picture
  56.  */
  57. #define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
  58.  
  59. /**
  60.  * A private definition to help overloading picture release
  61.  */
  62. typedef struct picture_release_sys_t picture_release_sys_t;
  63.  
  64. /**
  65.  * Video picture
  66.  *
  67.  * Any picture destined to be displayed by a video output thread should be
  68.  * stored in this structure from it's creation to it's effective display.
  69.  * Picture type and flags should only be modified by the output thread. Note
  70.  * that an empty picture MUST have its flags set to 0.
  71.  */
  72. struct picture_t
  73. {
  74.     /**
  75.      * The properties of the picture
  76.      */
  77.     video_frame_format_t format;
  78.  
  79.     /** Picture data - data can always be freely modified, but p_data may
  80.      * NEVER be modified. A direct buffer can be handled as the plugin
  81.      * wishes, it can even swap p_pixels buffers. */
  82.     uint8_t        *p_data;
  83.     void           *p_data_orig;                /**< pointer before memalign */
  84.     plane_t         p[PICTURE_PLANE_MAX];     /**< description of the planes */
  85.     int             i_planes;                /**< number of allocated planes */
  86.  
  87.     /** \name Type and flags
  88.      * Should NOT be modified except by the vout thread
  89.      * @{*/
  90.     int             i_status;                             /**< picture flags */
  91.     int             i_type;                /**< is picture a direct buffer ? */
  92.     bool            b_slow;                 /**< is picture in slow memory ? */
  93.     /**@}*/
  94.  
  95.     /** \name Picture management properties
  96.      * These properties can be modified using the video output thread API,
  97.      * but should never be written directly */
  98.     /**@{*/
  99.     unsigned        i_refcount;                  /**< link reference counter */
  100.     mtime_t         date;                                  /**< display date */
  101.     bool            b_force;
  102.     /**@}*/
  103.  
  104.     /** \name Picture dynamic properties
  105.      * Those properties can be changed by the decoder
  106.      * @{
  107.      */
  108.     bool            b_progressive;          /**< is it a progressive frame ? */
  109.     bool            b_top_field_first;             /**< which field is first */
  110.     unsigned int    i_nb_fields;                  /**< # of displayed fields */
  111.     int8_t         *p_q;                           /**< quantification table */
  112.     int             i_qstride;                    /**< quantification stride */
  113.     int             i_qtype;                       /**< quantification style */
  114.     /**@}*/
  115.  
  116.     /** Private data - the video output plugin might want to put stuff here to
  117.      * keep track of the picture */
  118.     picture_sys_t * p_sys;
  119.  
  120.     /** This way the picture_Release can be overloaded */
  121.     void (*pf_release)( picture_t * );
  122.     picture_release_sys_t *p_release_sys;
  123.  
  124.     /** Next picture in a FIFO a pictures */
  125.     struct picture_t *p_next;
  126. };
  127.  
  128. /**
  129.  * This function will create a new picture.
  130.  * The picture created will implement a default release management compatible
  131.  * with picture_Hold and picture_Release. This default management will release
  132.  * p_sys, p_q, p_data_orig fields if non NULL.
  133.  */
  134. VLC_EXPORT( picture_t *, picture_New, ( vlc_fourcc_t i_chroma, int i_width, int i_height, int i_sar_num, int i_sar_den ) );
  135.  
  136. /**
  137.  * This function will create a new picture using the given format.
  138.  *
  139.  * When possible, it is preferred to use this function over picture_New
  140.  * as more information about the format is kept.
  141.  */
  142. VLC_EXPORT( picture_t *, picture_NewFromFormat, ( const video_format_t *p_fmt ) );
  143.  
  144. /**
  145.  * Resource for a picture.
  146.  */
  147. typedef struct
  148. {
  149.     picture_sys_t *p_sys;
  150.  
  151.     /* Plane resources
  152.      * XXX all fields MUST be set to the right value.
  153.      */
  154.     struct
  155.     {
  156.         uint8_t *p_pixels;  /**< Start of the plane's data */
  157.         int i_lines;        /**< Number of lines, including margins */
  158.         int i_pitch;        /**< Number of bytes in a line, including margins */
  159.     } p[PICTURE_PLANE_MAX];
  160.  
  161. } picture_resource_t;
  162.  
  163. /**
  164.  * This function will create a new picture using the provided resource.
  165.  *
  166.  * If the resource is NULL then a plain picture_NewFromFormat is returned.
  167.  */
  168. VLC_EXPORT( picture_t *, picture_NewFromResource, ( const video_format_t *, const picture_resource_t * ) );
  169.  
  170. /**
  171.  * This function will force the destruction a picture.
  172.  * The value of the picture reference count should be 0 before entering this
  173.  * function.
  174.  * Unless used for reimplementing pf_release, you should not use this
  175.  * function but picture_Release.
  176.  */
  177. VLC_EXPORT( void, picture_Delete, ( picture_t * ) );
  178.  
  179. /**
  180.  * This function will increase the picture reference count.
  181.  * It will not have any effect on picture obtained from vout
  182.  *
  183.  * It returns the given picture for convenience.
  184.  */
  185. static inline picture_t *picture_Hold( picture_t *p_picture )
  186. {
  187.     if( p_picture->pf_release )
  188.         p_picture->i_refcount++;
  189.     return p_picture;
  190. }
  191. /**
  192.  * This function will release a picture.
  193.  * It will not have any effect on picture obtained from vout
  194.  */
  195. static inline void picture_Release( picture_t *p_picture )
  196. {
  197.     /* FIXME why do we let pf_release handle the i_refcount ? */
  198.     if( p_picture->pf_release )
  199.         p_picture->pf_release( p_picture );
  200. }
  201.  
  202. /**
  203.  * This function will return true if you are not the only owner of the
  204.  * picture.
  205.  *
  206.  * It is only valid if it is created using picture_New.
  207.  */
  208. static inline bool picture_IsReferenced( picture_t *p_picture )
  209. {
  210.     return p_picture->i_refcount > 1;
  211. }
  212.  
  213. /**
  214.  * Cleanup quantization matrix data and set to 0
  215.  */
  216. static inline void picture_CleanupQuant( picture_t *p_pic )
  217. {
  218.     free( p_pic->p_q );
  219.     p_pic->p_q = NULL;
  220.     p_pic->i_qstride = 0;
  221.     p_pic->i_qtype = 0;
  222. }
  223.  
  224. /**
  225.  * This function will copy all picture dynamic properties.
  226.  */
  227. static inline void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src )
  228. {
  229.     p_dst->date = p_src->date;
  230.     p_dst->b_force = p_src->b_force;
  231.  
  232.     p_dst->b_progressive = p_src->b_progressive;
  233.     p_dst->i_nb_fields = p_src->i_nb_fields;
  234.     p_dst->b_top_field_first = p_src->b_top_field_first;
  235.  
  236.     /* FIXME: copy ->p_q and ->p_qstride */
  237. }
  238.  
  239. /**
  240.  * This function will reset a picture informations (properties and quantizers).
  241.  * It is sometimes useful for reusing pictures (like from a pool).
  242.  */
  243. VLC_EXPORT( void, picture_Reset, ( picture_t * ) );
  244.  
  245. /**
  246.  * This function will copy the picture pixels.
  247.  * You can safely copy between pictures that do not have the same size,
  248.  * only the compatible(smaller) part will be copied.
  249.  */
  250. VLC_EXPORT( void, picture_CopyPixels, ( picture_t *p_dst, const picture_t *p_src ) );
  251. VLC_EXPORT( void, plane_CopyPixels, ( plane_t *p_dst, const plane_t *p_src ) );
  252.  
  253. /**
  254.  * This function will copy both picture dynamic properties and pixels.
  255.  * You have to notice that sometime a simple picture_Hold may do what
  256.  * you want without the copy overhead.
  257.  * Provided for convenience.
  258.  *
  259.  * \param p_dst pointer to the destination picture.
  260.  * \param p_src pointer to the source picture.
  261.  */
  262. static inline void picture_Copy( picture_t *p_dst, const picture_t *p_src )
  263. {
  264.     picture_CopyPixels( p_dst, p_src );
  265.     picture_CopyProperties( p_dst, p_src );
  266. }
  267.  
  268. /**
  269.  * This function will export a picture to an encoded bitstream.
  270.  *
  271.  * pp_image will contain the encoded bitstream in psz_format format.
  272.  *
  273.  * p_fmt can be NULL otherwise it will be set with the format used for the
  274.  * picture before encoding.
  275.  *
  276.  * i_override_width/height allow to override the width and/or the height of the
  277.  * picture to be encoded:
  278.  *  - if strictly lower than 0, the original dimension will be used.
  279.  *  - if equal to 0, it will be deduced from the other dimension which must be
  280.  *  different to 0.
  281.  *  - if strictly higher than 0, it will override the dimension.
  282.  * If at most one of them is > 0 then the picture aspect ratio will be kept.
  283.  */
  284. VLC_EXPORT( int, picture_Export, ( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt, picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width, int i_override_height ) );
  285.  
  286. /**
  287.  * This function will setup all fields of a picture_t without allocating any
  288.  * memory.
  289.  * XXX The memory must already be initialized.
  290.  * It does not need to be released.
  291.  *
  292.  * It will return VLC_EGENERIC if the core does not understand the requested
  293.  * format.
  294.  *
  295.  * It can be useful to get the properties of planes.
  296.  */
  297. VLC_EXPORT( int, picture_Setup, ( picture_t *, vlc_fourcc_t i_chroma, int i_width, int i_height, int i_sar_num, int i_sar_den ) );
  298.  
  299. /*****************************************************************************
  300.  * Flags used to describe the status of a picture
  301.  *****************************************************************************/
  302.  
  303. /* Picture type
  304.  * FIXME are the values meaningfull ? */
  305. enum
  306. {
  307.     EMPTY_PICTURE = 0,                             /* empty buffer */
  308.     MEMORY_PICTURE = 100,                 /* heap-allocated buffer */
  309.     DIRECT_PICTURE = 200,                         /* direct buffer */
  310. };
  311.  
  312. /* Picture status */
  313. enum
  314. {
  315.     FREE_PICTURE,                              /* free and not allocated */
  316.     RESERVED_PICTURE,                          /* allocated and reserved */
  317.     READY_PICTURE,                                  /* ready for display */
  318.     DISPLAYED_PICTURE,                   /* been displayed but is linked */
  319.     DESTROYED_PICTURE,                     /* allocated but no more used */
  320. };
  321.  
  322. /* Quantification type */
  323. enum
  324. {
  325.     QTYPE_NONE,
  326.  
  327.     QTYPE_MPEG1,
  328.     QTYPE_MPEG2,
  329.     QTYPE_H264,
  330. };
  331.  
  332. /*****************************************************************************
  333.  * Shortcuts to access image components
  334.  *****************************************************************************/
  335.  
  336. /* Plane indices */
  337. enum
  338. {
  339.     Y_PLANE = 0,
  340.     U_PLANE = 1,
  341.     V_PLANE = 2,
  342.     A_PLANE = 3,
  343. };
  344.  
  345. /* Shortcuts */
  346. #define Y_PIXELS     p[Y_PLANE].p_pixels
  347. #define Y_PITCH      p[Y_PLANE].i_pitch
  348. #define U_PIXELS     p[U_PLANE].p_pixels
  349. #define U_PITCH      p[U_PLANE].i_pitch
  350. #define V_PIXELS     p[V_PLANE].p_pixels
  351. #define V_PITCH      p[V_PLANE].i_pitch
  352. #define A_PIXELS     p[A_PLANE].p_pixels
  353. #define A_PITCH      p[A_PLANE].i_pitch
  354.  
  355. /**@}*/
  356.  
  357. #endif /* VLC_PICTURE_H */
  358.